Inside Macintosh: QuickTime
The Movie Toolbox provides a number of functions that allow your application to determine and change the display characteristics of movies and tracks. These functions are discussed in the following sections. Before using any of these functions, you should be familiar with the way in which the Movie Toolbox displays movies. See the discussion of spatial properties in "About Movies" .
You can use the SetMovieGWorld and GetMovieGWorld functions to work with a movie's graphics world. See Inside Macintosh: Imaging for more information about graphics worlds.
Your application can work with a movie's matrix by calling the GetMovieMatrix and SetMovieMatrix functions, and it can work with a track's matrix with the GetTrackMatrix and SetTrackMatrix functions. Then you can perform operations on matrices with the Movie Toolbox's matrix functions described in "Matrix Functions," .
The following functions affect the displayed movie and its tracks in the final display coordinate system. The SetMovieGWorld and GetMovieGWorld functions let you work with a movie's display destination. The GetMovieBox and SetMovieBox functions allow you to work with a movie's boundary rectangle and its associated transformations. Alternatively, you can use the GetMovieMatrix and SetMovieMatrix functions to work directly with a movie's transformation matrix. The GetMovieDisplayBoundsRgn function determines a movie's boundary region at the current movie time. On the other hand, the GetMovieSegmentDisplayBoundsRgn function determines a movie's boundary region over a specified time segment. You can use the GetMovieDisplayClipRgn and SetMovieDisplayClipRgn functions to work with a movie's display clipping region.
The GetTrackDisplayBoundsRgn and GetTrackSegmentDisplayBoundsRgn functions determine a track's final boundary region. You can use the GetTrackLayer and SetTrackLayer functions to control the drawing order of tracks within a movie.
A number of functions affect a movie's display boundaries before any display transformations--these functions operate in the movie's display coordinate system. You can use the GetMovieClipRgn and SetMovieClipRgn functions to work with a movie's clipping region--that is, the clipping region that is applied before the movie display transformation. Use the GetMovieBoundsRgn function to determine a movie's boundary region at the current movie time.
Use the GetTrackMovieBoundsRgn function to work with a track's boundary region after matrix transformations have placed the track into the movie's display system. The SetTrackMatrix and GetTrackMatrix functions let you define a track's matrix transformations.
The Movie Toolbox provides several functions that affect a track's display boundaries--these functions operate in the track's display coordinate system before any other display transformations are applied. The GetTrackDimensions and SetTrackDimensions functions allow you to establish a track's coordinate system and to establish a track's source rectangle.
Note
A track's source rectangle defines the coordinate system of the track. You specify the dimensions of the rectangle by providing the coordinates of the lower-right corner of the rectangle. The Movie Toolbox sets the upper-left corner to (0,0) in the track's coordinate system.
You can use the GetTrackBoundsRgn function to determine a track's boundary region. The GetTrackClipRgn and SetTrackClipRgn functions let you work with a track's clipping region. You can use the GetTrackMatte and SetTrackMatte functions to establish a track's matte. The DisposeMatte function allows you to dispose of a matte once you are finished with it.
Applications use SetMovieGWorld to associate a QuickTime movie with a drawing destination called a GWorld. The SetMovieGWorld function allows your application to establish a movie's display coordinate system by setting the graphics world for displaying a movie.
pascal void SetMovieGWorld (Movie theMovie, CGrafPtr port,
GDHandle gdh);
The Movie Toolbox automatically sets the graphics world when you create a new movie. Be sure that your application's graphics port is valid or that you specify a valid graphics port with the port parameter. If you pass nil for the port parameter, make sure the current graphics world is valid.
When you use SetMovieGWorld , the Movie Toolbox remembers the current background color and background pattern. These are used for erasing in the default movie uncover function.
Applications concerned with playback and rendering performance should call SetMovieGWorld only when necessary. Most applications only call SetMovieGWorld once when a movie is created. Some applications, however, display a single movie in several different windows. These applications must call SetMovieGWorld more than once to ensure that the movie is set to the correct destination. Changing the destination GWorld can be a time-consuming operation, however, so applications should be optimized to avoid unnecessary calls to SetMovieGWorld.
When the movie's GWorld is set, QuickTime needs to rebuild its drawing pipeline. This can require reallocating QuickTime's internal buffers and renegotiating the drawing pipeline with Image Decompressors. This work is not actually done in SetMovieGWorld, but during the next call to MoviesTask, so profiling the calls to QuickTime will only indicate that MoviesTask is taking longer than usual, not that SetMovieGWorld is the cause of the problem.
One of the common mistakes applications make is to call SetMovieGWorld between calls to MoviesTask. In this case, the GWorld being set is always the same. It might seem reasonable to expect QuickTime to ignore calls to SetMovieGWorld when the GWorld isn't being changed. However, because of the way GWorlds are allocated, it is possible to dispose of one GWorld and allocate another with the same address but different properties. Consequently, QuickTime doesn't ignore calls to SetMovieGWorld, even if the address of the GWorld hasn't changed.
Your application can determine a movie's graphics world by calling the GetMovieGWorld function.
pascal void GetMovieGWorld (Movie theMovie, CGrafPtr *port,
GDHandle *gdh);
The SetMovieBox function sets a movie's boundary rectangle, or movie box, which is a rectangle that encompasses the spatial representation of all of the movie's enabled tracks. The movie box is in the display coordinate system.
pascal void SetMovieBox (Movie theMovie, const Rect *boxRect);
The Movie Toolbox changes the rectangle by modifying the translation and scale values of the movie's matrix to accommodate the new boundary rectangle.
The movie box might not have its upper-left corner set at (0,0) in its display window when the movie is first loaded. Consequently, your application may need to adjust the position of the movie box so that it appears in the appropriate location within your application's document window. If you don't reset the movie position, the movie might not be visible when it starts playing.
The following sample code demonstrates how to move the boundary rectangle.
GetMovieBox (movie, &movieBox);
OffsetRect (&movieBox, -movieBox.left, -movieBox.top);
SetMovieBox (movie, &movieBox);
You can modify the movie's matrix directly by calling the SetMovieMatrix function, which is described on SetMovieMatrix . You can retrieve a movie's boundary rectangle by calling the GetMovieBox function, which is described in the next section.
The GetMovieBox function returns a movie's boundary rectangle, which is a rectangle that encompasses all of the movie's enabled tracks. The movie box is in the coordinate system of the movie's graphics world and defines the movie's boundaries over the entire duration of the movie. The movie's boundary rectangle defines the size and shape of the movie before the Movie Toolbox applies the display clipping region.
pascal void GetMovieBox (Movie theMovie, Rect *boxRect);
The GetMovieDisplayBoundsRgn function allows your application to determine a movie's display boundary region. The display boundary region encloses all of a movie's enabled tracks after the track matrix, track clip, movie matrix, and movie clip have been applied to all of the movie's tracks. This region is in the display coordinate system of the movie's graphics world. The movie's boundary rectangle encloses this region. For more on boundary regions and matrices for movies and tracks, see "Spatial Properties," which begins on Spatial Properties .
pascal RgnHandle GetMovieDisplayBoundsRgn (Movie theMovie);
The Movie Toolbox derives the display boundary region only from enabled tracks, and only from those tracks that are used in the current display mode (that is, movie, poster, or preview). The display boundary region is valid for the current movie time.
The GetMovieDisplayBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this handle when you are done with it. If the movie does not have a spatial representation at the current movie time, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The GetMovieSegmentDisplayBoundsRgn function allows your application to determine a movie's display boundary region during a specified segment. The display boundary region encloses all of a movie's enabled tracks after the track matrix, track clip, movie matrix, and movie clip have been applied to all of the movie's tracks. This region is in the display coordinate system. The movie's boundary encloses this region. For more on boundary regions and matrices for movies and tracks, see "Spatial Properties," which begins on Spatial Properties .
pascal RgnHandle GetMovieSegmentDisplayBoundsRgn (Movie theMovie,
TimeValue time,
TimeValue
duration);
The Movie Toolbox derives the display boundary region only from enabled tracks and only from those tracks that are used in the current display mode (that is, movie, poster, or preview). If you want to determine the boundary region that applies to the current movie time, you can use GetMovieDisplayBoundsRegion , which is described in the previous section.
The GetMovieSegmentDisplayBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the movie does not have a spatial representation during the specified segment, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The SetMovieDisplayClipRgn function allows your application to establish a movie's current display clipping region.
pascal void SetMovieDisplayClipRgn (Movie theMovie,
RgnHandle theClip);
The display clipping region defines any final clipping that is applied to the movie before it is displayed, and it is valid for the entire duration of the movie. You must use this region to clip a movie because the Movie Toolbox ignores the clip region of the movie's graphics world during display processing.
Note that the display clipping region is not saved with the movie.
Do not use the SetMovieDisplayClipRgn function when you are using a movie controller component--use the movie controller component function MCSetClip instead. For details on the MCSetClip function, see the chapter "Movie Controller Components" in Inside Macintosh: QuickTime Components.
The GetMovieDisplayClipRgn function allows your application to determine a movie's current display clipping region.
pascal RgnHandle GetMovieDisplayClipRgn (Movie theMovie);
The display clipping region defines the final clipping that is applied to the movie before it is displayed. The display clipping region is valid for the entire duration of the movie.
Note that the display clipping region is not saved with the movie.
The GetMovieDisplayClipRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the function could not satisfy your request or if there is no display clipping region defined for the movie, the function sets the returned handle to nil .
The GetTrackDisplayBoundsRgn function allows your application to determine the region a track occupies in a movie's graphics world.
pascal RgnHandle GetTrackDisplayBoundsRgn (Track theTrack);
This region is in the display coordinate system. This region, when intersected with the movie's display clipping region, describes which pixels in the movie's graphics world display information from the specified track. This region is valid for the current movie time.
The GetTrackDisplayBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the track does not have a spatial representation at the current movie time, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The GetTrackSegmentDisplayBoundsRgn function allows your application to determine the region a track occupies in a movie's graphics world during a specified segment.
pascal RgnHandle GetTrackSegmentDisplayBoundsRgn (Track theTrack,
TimeValue time,
TimeValue duration);
This region is in the display coordinate system. When combined with the movie's display clipping region, this region describes which pixels in the movie's graphics world display information from the specified track.
This region is valid for the specified segment.
The GetTrackSegmentDisplayBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the track does not have a spatial representation during the specified segment, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The SetTrackLayer function allows your application to set a track's layer.
pascal void SetTrackLayer (Track theTrack, short layer);
Track layers are numbered from -32,768 through 32,767. You can use layers to control how tracks are combined to create a movie. The Movie Toolbox displays layers by layer number. That is, the Movie Toolbox displays higher-numbered layers first, placing lower-numbered layers on top of them. If your movie has more than one track in the same layer, the Movie Toolbox displays those layers in order by track index value, displaying higher-numbered tracks first.
The GetTrackLayer function allows your application to retrieve a track's layer.
pascal short GetTrackLayer (Track theTrack);
The GetTrackLayer function returns an integer that contains the track's layer number. Tracks are numbered from -32,768 through 32,767. You can use layers to control how tracks are combined to create a movie. The Movie Toolbox displays layers by layer number. That is, the Movie Toolbox displays higher-numbered layers first, placing lower-numbered layers on top of them. If your movie has more than one track in the same layer, the Movie Toolbox displays those layers in order by track index value, displaying higher-numbered tracks first.
The SetMovieMatrix function allows your application to set a movie's transformation matrix. The Movie Toolbox uses a movie's matrix to map a movie from its display coordinate system to its graphics world. You can retrieve a movie's matrix with the GetMovieMatrix function, which is described in the next section.
pascal void SetMovieMatrix (Movie theMovie,
const MatrixRecord *matrix);
The Movie Toolbox provides a number of functions that allow you to manipulate movie matrices. See "Matrix Functions," which begins on Matrix Functions , for information about these functions.
The GetMovieMatrix function allows your application to retrieve a movie's transformation matrix.
pascal void GetMovieMatrix (Movie theMovie, MatrixRecord *matrix);
The Movie Toolbox uses a movie's matrix to map a movie from its coordinate system to the display coordinate system.
You can set a movie's matrix with the SetMovieMatrix function, which is described in the previous section.
The Movie Toolbox provides a number of functions that allow you to manipulate movie matrices. See "Matrix Functions," which begins on Matrix Functions , for information about these functions.
The GetMovieBoundsRgn function allows your application to determine a movie's boundary region.
pascal RgnHandle GetMovieBoundsRgn (Movie theMovie);
The movie boundary region encloses all of a movie's tracks after the union of the track clip and the track matrix has been applied to all the movie's tracks (but not to the movie itself). This region is in the movie's display coordinate system.
The Movie Toolbox derives the boundary region only from enabled tracks, and only from those tracks that are used in the current display mode (that is, movie or preview). The boundary region is valid for the current movie time.
The GetMovieBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the movie does not have a spatial representation at the current time, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The GetTrackMovieBoundsRgn function allows your application to determine the region the track occupies in a movie's boundary region. This region is in the display coordinate system of the movie. The Movie Toolbox determines this region by applying the track's clipping region and matrix. This region is valid only for the current movie time.
pascal RgnHandle GetTrackMovieBoundsRgn (Track theTrack);
The GetTrackMovieBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the track does not have a spatial representation at the current movie time, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The SetMovieClipRgn function allows your application to establish a movie's clipping region.
pascal void SetMovieClipRgn (Movie theMovie, RgnHandle theClip);
The GetMovieClipRgn function allows your application to determine a movie's clipping region.
pascal RgnHandle GetMovieClipRgn (Movie theMovie);
The clipping region defines any clipping that is applied to the movie before it is mapped to its graphics world by applying the movie's matrix. The clipping region is in the movie's display coordinate system and is valid for the entire duration of the movie.
The GetMovieClipRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the function could not satisfy your request or if there is no clipping region defined for the movie, it sets the returned handle to nil .
The clipping region is saved with the movie when your application saves the movie.
The SetTrackMatrix function allows your application to establish a track's transformation matrix.
pascal void SetTrackMatrix (Track theTrack,
const MatrixRecord *matrix);
The Movie Toolbox uses a track's matrix to map a track from its own coordinate system into a movie's display coordinate system.
You can get a track's matrix with the GetTrackMatrix function, which is described in the next section.
The Movie Toolbox provides a number of functions that allow you to manipulate track matrices. See "Matrix Functions," for information about these functions.
The GetTrackMatrix function allows your application to retrieve a track's transformation matrix.
pascal void GetTrackMatrix (Track theTrack, MatrixRecord *matrix);
The Movie Toolbox uses a track's matrix to map a track from its own coordinate system into a movie's display coordinate system.
You can set a track's matrix with the SetTrackMatrix function, which is described in the previous section.
The Movie Toolbox provides a number of functions that allow you to manipulate track matrices. See "Matrix Functions" for information about these functions.
The GetTrackBoundsRgn function allows the media to limit the size of the track boundary rectangle. Therefore, the region returned by GetTrackBoundsRgn may not be rectangular and may be smaller than the track boundary region.
pascal RgnHandle GetTrackBoundsRgn (Track theTrack);
The GetTrackBoundsRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the track does not have a spatial representation during the specified segment, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to nil .
The SetTrackDimensions function allows your application to establish a track's source, or display, rectangle.
pascal void SetTrackDimensions (Track theTrack, Fixed width,
Fixed height);
A track's source rectangle defines the coordinate system of the track. You specify the dimensions of the rectangle by providing the coordinates of the lower-right corner of the rectangle. The Movie Toolbox sets the upper-left corner to (0,0) in the track's coordinate system.
If you change the dimensions of an existing track, the media data is scaled to fit into the new rectangle.
The GetTrackDimensions function allows your application to determine a track's source, or display, rectangle.
pascal void GetTrackDimensions (Track theTrack, Fixed *width,
Fixed *height);
The SetTrackClipRgn function allows your application to set the clipping region of a track.
pascal void SetTrackClipRgn (Track theTrack, RgnHandle theClip);
The GetTrackClipRgn function allows your application to determine the clipping region of a track.
pascal RgnHandle GetTrackClipRgn (Track theTrack);
The clipping region is in the track's coordinate system. The Movie Toolbox applies the clipping region to a track before it applies the track's matrix. This region is valid for the entire duration of the track.
The GetTrackClipRgn function allocates the region and returns a handle to the region. Your application must dispose of this region when you are done with it. If the function could not satisfy your request or if there is no clipping region defined for the track, it sets the returned handle to nil .
The SetTrackMatte function allows your application to set a track's matte. The matte defines which of the track's pixels are displayed in a movie. You must specify the matte in a pixel map structure.
pascal void SetTrackMatte (Track theTrack, PixMapHandle theMatte);
The Movie Toolbox displays the weighted average of the track and its destination based on the corresponding pixel in the matte (this feature is fully functional in System 7 and is approximated in System 6).
Note that the track matte must have its boundaries defined by the track rectangle.
You can retrieve a track's matte by calling the GetTrackMatte function, which is described in the next section. Listing 15 shows how to use the SetTrackMatte and GetTrackMatte functions to create a track matte.
The GetTrackMatte function allows your application to retrieve a copy of a track's matte. The matte defines which of the track's pixels are displayed in a movie, and it is valid for the entire duration of the movie. This function returns the matte in a pixel map structure. You may use QuickDraw functions to manipulate the returned matte. However, you should use the Movie Toolbox's DisposeMatte function (described in the next section) to dispose of the matte when you are finished with it.
pascal PixMapHandle GetTrackMatte (Track theTrack);
The GetTrackMatte function returns a handle to the matte. Your application must dispose of this handle when you are done with it--you must use the DisposeMatte function, which is described in the next section, to dispose of the matte. If the function could not satisfy your request, it sets the returned handle to nil .
You can establish a track's matte by calling the SetTrackMatte function, which is described in the previous section. Listing 15 shows how to use the SetTrackMatte and GetTrackMatte functions to create a track matte.
The DisposeMatte function disposes of a matte that you obtained from the GetTrackMatte function, which is described in the previous section.
pascal void DisposeMatte (PixMapHandle theMatte);